docs(ops): record the staging cutover and correct two rite-calendar runbook steps (#955) - #966

…ctions (#955)

The rite-calendar rollout is complete on the dev/staging vhost. Running it
surfaced two places where the runbook's instructions do not match how that
deployment actually works; both are corrected here alongside the cutover
date the runbook asks for.

**Step 4 runs itself on a deployed vhost.** `bin/doctrine-migrations` is
excluded from the rsync payload precisely because migrations are applied
in-process, and `deploy.yaml` POSTs `/_ops/migrate` after every rsync — so
`composer db:migrate` cannot run there at all; it fails with
`Could not open input file: bin/doctrine-migrations`. The migration landed
at deploy time: `Version20260901130000` executed 2026-09-01T20:23:37Z, in
the same deploy that shipped #965, which is what the Staging row now
records.

That also inverts the documented Step 3 → Step 4 order, and the sequence
cannot be rearranged, so the runbook now says so rather than leaving an
operator to discover it. The effect is to widen the Step 2 window the
runbook already describes, not to add a hazard: change-request rows named
`rite_calendar` while their tuples were still legacy, so those requests
queued for a reviewer instead of auto-approving, and resumed when Step 3
ran. Nothing was corrupted.

**Step 1's re-pin command is for a checkout, not the vhost.**
`./scripts/setup-openfga.sh --update-env` run from a local clone resolves
whatever store that clone points at — a local dev store, not production —
and writes those values. The deployed pin against the production store is
one file, `api/dev/.env.staging`, the only `.env*` that deployment has.

The re-pin shape is documented because getting it wrong took the API down
for ~2 minutes on 2026-09-01: a shell redirect truncates its destination
BEFORE the command on its left runs, so `cat "$tmp" > .env.staging` where
`$tmp` was a `mktemp` file owned by `ubuntu` (mode 600, unreadable to the
user the write ran as) emptied the live file and then failed to refill it.
phpdotenv reads per request, so a zero-byte `.env.staging` is an immediate
outage. `cp` opens its source before truncating its destination and is the
right primitive; the whole pipeline must run as the file's owner.

Verified end to end against production: model `01M1FHYEDWG8E1CKD4VAKCYZ9V`
carries `rite_calendar`, the pin is updated, the tuple migration copied 1
of 1 candidate with 0 skipped, and the copied tuple was confirmed by
reading it back from the store rather than trusting the script's report.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kGisCz5Gscvc9GGRQAUpz

All six findings were valid; each is verified below rather than taken on
faith.

**Auto-approval does not resume retroactively.** The claim that queued
change requests "resume the moment Step 3 runs" was wrong.
`ChangeRequestSourceDataWriter` calls `ChangeRequestReview::administers()`
at submit time and records the batch as `submitted` when it is false;
nothing re-evaluates it afterwards. So a request that queued during the
window stays queued and needs an explicit reviewer approval — only new
submissions auto-approve again. The same error was already in the Step 2
text ("queued requests are approved normally once the tuples are
migrated"), which was not part of this PR's changes; fixed there too rather
than leaving a known-false statement two sections above the corrected one.
Reviewer-queue visibility, by contrast, IS evaluated per query and does
return on its own — the two are now distinguished.

**The env edit is now atomic.** `cp` onto the live file is not: it
truncates and rewrites in place, so a request landing mid-write reads a
partial `.env`. The block now seeds a temp in the SAME directory with
`cp -p` (carrying owner/group/mode), redirects into that temp rather than
the live file, greps it for the expected new value, and `mv`s it into place
— a rename within one directory, so no reader ever sees a half-written
file — with `|| rm -f` cleanup. Tested both paths: the success path
preserves mode 640 and leaves no temp; the failure path leaves the live
file byte-intact and still cleans up.

**The deploy token no longer goes in argv.** `-H "X-Deploy-Token: $TOKEN"`
puts a shared secret in the process argument list, readable by any other
user on the VPS via `ps`. It now goes through a curl config on stdin
(`-K -`), verified against a local server: the header arrives intact and
the value never appears in argv. `--proto '=https'` is added so curl
refuses to send it over cleartext rather than trusting a route-level
redirect — verified: `curl: (1) Protocol "http" not supported or disabled`.

**The token is loaded rather than assumed.** The snippet referenced
`$DEPLOY_TOKEN` without saying where it comes from; unset, the request goes
out with an empty header and `DeployTokenMiddleware` fails closed. It now
extracts it from the host's env file and unsets it afterwards. Checked
against the real file: the value is unquoted, so the `sed` form is correct
there.

Also reworded the ownership sentence to "unreadable to the user performing
the write".

Docs only. `composer lint:md` clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kGisCz5Gscvc9GGRQAUpz

**Token read.** The status snippet read `.env.staging` relative to whatever
the current directory happened to be, and did not check the result. A wrong
path yields an EMPTY token, and the request then goes out with an empty
header and returns a fail-closed 401/403 that reads like a token problem
rather than a path problem. It now reads by absolute path and guards on
non-empty before calling curl. Verified both paths against a local server:
a valid token arrives as the header, and a wrong path prints the diagnostic
and skips curl.

The guard is an `if`/`else`, not an `exit` — a runbook snippet is pasted
into an interactive shell, where `exit 1` logs the operator out. `sudo` is
deliberately not added for this read either: `.env.staging` is mode 640,
group `psacln`, and the operator account is in that group, so the plain
read is what actually works there.

**PR number.** `#965` appeared exactly once, in the Staging cutover row,
while the rest of the document refers to `#955` throughout — so the one
number a reader cannot resolve was the one naming the deployed build. Step
2 now names the PR alongside the issue once, which anchors it, rather than
rewriting the four other "#955" references that read correctly as the issue.

Docs only. `composer lint:md` clean.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018kGisCz5Gscvc9GGRQAUpz